window | NN 2 IE 3 DOM n/a | ||||
The window object represents the browser window or frame in which document content is displayed. The window object plays a vital role in scripting when scripts must communicate with document objects located in other frames or subwindows. Internet Explorer 4 includes a special kind of subwindow called a modal dialog window. Modal dialog windows have most, but not all, window object properties and methods available to them. | |||||
Object Model Reference
|
clientInformation | NN n/a IE 4 DOM n/a | ||
Read-only | |||
Returns the navigator object. The navigator object is named after a specific browser brand; the clientInformation property is a nondenominational way of accessing important environment variables that have historically been available through properties and methods of the navigator object. In Internet Explorer, you can substitute window.clientInformation for any reference that begins with navigator. | |||
Exampleif (parseInt(window.clientInformation.appVersion) >= 4) { } | |||
Value The navigator object. | |||
|
closed | NN 3 IE 4 DOM n/a | ||
Read-only | |||
Boolean value that says whether the referenced window is closed. A value of true means the window is no longer available for referencing its objects or script components. This is used most often to check whether a user has closed a subwindow generated by the window.open( ) method. | |||
Exampleif (!newWindow.closed) { newWindow.document.write("<HTML><BODY><H1>Howdy!</H1></BODY></HTML>") newWindow.document.close( ) } | |||
Value Boolean value: true | false. | |||
|
defaultStatus | NN 2 IE 3 DOM n/a | ||
Read/Write | |||
The default message displayed in the browser window's status bar when no browser loading activity is occurring. To temporarily change the message (during mouse rollovers, for example), set the window's status property. Most scriptable browsers and versions have difficulty managing the setting of the defaultStatus property. Expect odd behavior. | |||
Examplewindow.defaultStatus = "Make it a great day!" | |||
Value Any string value. | |||
|
dialogArguments | NN n/a IE 4 DOM n/a | ||
Read-only | |||
String or other data type passed as extra arguments to a modal dialog window created with the showModalDialog( ) method. This property is best accessed by a script in the document occupying the modal dialog to retrieve whatever data is passed to the new window as arguments. It is up to your script to parse the data if you include more than one argument nugget separated by whatever argument delimiter you choose. | |||
Examplevar allArgs = window.dialogArguments var firstArg = allArgs.substring(0, allArgs.indexOf(";")) | |||
Value String, number, or array. | |||
|
dialogHeight, dialogWidth | NN n/a IE 4 DOM n/a | ||
Read/Write | |||
Length values of height and width of a modal dialog window created with the showDialog( ) method. Although Internet Explorer 4 does not balk at modifying these properties (in a script running in the modal dialog window), the changed values are generally not reflected in a resized dialog window. Initial values are set as parameters to the showDialog( ) method. | |||
Examplevar outerWidth = window.dialogWidth | |||
Value String including the unit value. | |||
|
dialogLeft, dialogTop | NN n/a IE 4 DOM n/a | ||
Read/Write | |||
Offset distance of left and top edges of a modal dialog window (created with the showDialog( ) method) relative to the top-left corner of the video screen. Although Internet Explorer 4 does not balk at modifying these properties (in a script running in the modal dialog window), the changed values are generally not reflected in a repositioned dialog window. Initial values are set as parameters to the showDialog( ) method. | |||
Examplevar outerLeft = window.dialogLeft | |||
Value String including the unit value. | |||
|
event | NN n/a IE 4 DOM n/a | ||
Read-only | |||
Internet Explorer 4's event model generates an event object for each user or system event. This event object is a property of the window object. | |||
Exampleif (event.altKey) { } | |||
Value event object reference. | |||
|
history | NN 2 IE 3 DOM n/a | ||
Read-only | |||
Contains the history object for the current window or frame. For details, see the discussion of the history object. | |||
Exampleif (self.history.length > 4) { ... } | |||
Value history object reference. | |||
|
innerHeight, innerWidth | NN 4 IE n/a DOM n/a | ||
Read/Write | |||
The pixel measure of the height and width of the content region of a browser window or frame. This area is where the document content appears, exclusive of all window "chrome." | |||
Examplewindow.innerWidth = 600 window.innerHeight = 400 | |||
Value Integer. | |||
|
length | NN n/a IE 4 DOM n/a | ||
Read-only | |||
The number of frames (if any) nested within the current window. This value is the same as that returned by window.frames.length. When no frames are defined for the window, the value is zero. | |||
Exampleif (window.length > 0) { ... } | |||
Value Integer. | |||
|
location | NN 2 IE 3 DOM n/a | ||
Read/Write | |||
The URL of the document currently loaded in the window or frame. To navigate to another page, you assign a URL to the location.href property (or see the navigate( ) method for an IE-only alternative). | |||
Exampletop.location = "index.html" | |||
Value A full or relative URL as a string. | |||
|
name | NN 2 IE 3 DOM 1 | ||
Read/Write | |||
The identifier associated with a frame or subwindow for use as the value assigned to TARGET attributes or as script references to the frame/subwindow. For a frame, the value is usually assigned via the NAME attribute of the FRAME tag, but it can be modified by a script if necessary. The name of a subwindow is assigned as a parameter to the window.open( ) method. The primary browser window does not have a name by default. | |||
Exampleif (parent.frames[1].name == "main") { ... } | |||
Value Case-sensitive identifier that follows the rules of identifier naming: it may contain no whitespace, cannot begin with a numeral, and should avoid punctuation except for the underscore character. | |||
|
offscreenBuffering | NN n/a IE 4 DOM n/a | ||
Read/Write | |||
Whether the browser should use offscreen buffering to improve path animation performance. This property applies only to the Windows 95/NT operating system platforms. When the document loads, the property is set to auto. After that, a script may turn buffering on and off by assigning a Boolean value to this property. | |||
Examplewindow.offscreenBuffering = "true" | |||
Value Boolean value: true | false. | |||
|
opener | NN 3 IE 3 DOM n/a | ||
Read/Write | |||
Object reference to the window (or frame) that used a window.open( ) method to generate the current window. This property allows subwindows to assemble references to objects, variables, and functions in the originating window. To access document objects in the creating window, a reference can begin with opener and work its way through the regular document object hierarchy from there, as shown in the left side of the following example statement. The relationship between the opening window and the opened window is not strictly parent-child. The term "parent" has other connotations in scripted window and frame references. | |||
Exampleopener.document.forms[0].importedData.value = document.forms[0].entry.value | |||
Value window object reference. | |||
|
outerHeight, outerWidth | NN 4 IE n/a DOM n/a | ||
Read/Write | |||
The pixel measure of the height and width of the browser window or frame, including (for the top window) all toolbars, scollbars and other visible window "chrome." | |||
Examplewindow.outerWidth = 80 window.outerHeight = 600 | |||
Value Integer. | |||
|
pageXOffset, pageYOffset | NN 4 IE n/a DOM n/a | ||
Read-only | |||
The pixel measure of the amount of the page's content that has been scrolled upward and/or to the left. For example, if a document has been scrolled so that the topmost 100 pixels of the document (the "page") are not visible because the window is scrolled, the pageYOffset value for the window is 100. When a document is not scrolled, both values are zero. | |||
Examplevar vertScroll = self.pageYOffset | |||
Value Integer. | |||
|
parent | NN 2 IE 3 DOM n/a | ||
Read-only | |||
Returns a reference to the parent window object whose document defined the frameset in which the current frame is specified. Use parent in building a reference from one child frame to variables or methods in the parent document or to variables, methods, and objects in another child frame. For example, if a script in one child frame must reference the content of a text input form element in the other child frame (named "content"), the reference would be: parent.content.document.forms[0].entryField.value
For more deeply nested frames, you can access the parent of a parent with syntax such as: parent.parent.frameName. | |||
Exampleparent.frames[1].document.forms[0].companyName.value = "MegaCorp" | |||
Value window object reference. | |||
|
returnValue | NN n/a IE 4 DOM n/a | ||
Read/Write | |||
A value to be returned to the main window when the IE modal dialog window closes. The value assigned to this property in a script running in the dialog window is returned as the value to the showModalDialog( ) method in the main window. For example the document in the modal dialog window may have a statement that sets the returnValue property with information from the dialog: window.returnValue = window.document.forms[0].userName.value The dialog is created in the main document with a statement like the following: var userName = showModalDialog("userNamePrompt.html") Whatever value is assigned to returnValue in the dialog is then assigned to userName when the dialog box closes and script execution continues. | |||
Value Any scriptable data type. | |||
|
screen | NN n/a IE 4 DOM n/a | ||
Read-only | |||
Returns a reference to the screen object. Internet Explorer treats the screen object as a property of the window, even though the scope of the screen object transcends all windows or frames currently existing in the browser. Since the window reference is optional, syntax without the window reference works on Internet Explorer and Navigator when a common property is accessed. | |||
Examplevar howDeep = screen.availHeight | |||
Value Object reference. | |||
|
self | NN 2 IE 3 DOM n/a | ||
Read-only | |||
A reference to the current window or frame. This property is synonymous with window, but is sometimes used to improve clarity in a complex script that refers to many windows or frames. Never use the reference window.self to refer to the current window or frame. | |||
Exampleself.focus( ) | |||
Value window object reference. | |||
|
status | NN 2 IE 3 DOM n/a | ||
Read/Write | |||
Text of the status bar of the browser window. Setting the status bar to some message is recommended only for temporary messages, such as for mouse rollovers atop images, areas, or links. Double or single quotes in the message must be escaped (\'). Many users don't look for the status bar, so avoid putting mission-critical information there. Temporary messages conflict with browser-driven use of the status bar for loading progress and other purposes. To set the default status bar message (when all is at rest), see the defaultStatus property. | |||
Example<...onMouseOver="window.status='Table of Contents';return true" onMouseOut = "window.status = '';return true"> | |||
Value String. | |||
|
top | NN 2 IE 3 DOM n/a | ||
Read-only | |||
Object reference to the browser window. Script statements from inside nested frames can refer to the browser window properties and methods or to variables or functions stored in the document loaded in the topmost position. Do not begin a reference with window.top, just top. To replace a frameset with a new document that occupies the entire browser window, assign a URL to the top.location.href property. | |||
Exampletop.location.href = "tableOfContents.html" | |||
Value window object reference. | |||
|
alert( ) | NN 2 IE 3 DOM n/a | ||
alert(message) Displays an alert dialog box with a message of your choice. A single button lets the user close the dialog. The title bar of the window (and the "JavaScript Alert" legend in earlier browser versions) cannot be altered by script. | |||
Returned Value None. | |||
Parameters
|
back( ) | NN 4 IE n/a DOM n/a |
Navigates one step backward through the history list of the window or frame. | |
Returned Value None. | |
Parameters None. |
blur( ) | NN 3 IE 4 DOM n/a |
Removes focus from the window and fires an onBlur event (in IE). No other element necessarily receives focus as a result. | |
Returned Value None. | |
Parameters None. |
captureEvents( ) | NN 4 IE n/a DOM n/a | ||
captureEvents(eventTypeList) Instructs the browser to grab events of a specific type before they reach their intended target objects. The object invoking this method must then have event handlers defined for the given event types to process the event. | |||
Returned Value None. | |||
Parameters
|
clearInterval( ) | NN 4 IE 4 DOM n/a | ||
clearInterval(intervalID) Turns off the interval looping action referenced by the intervalID parameter. See setInterval( ) for how to initiate such a loop. | |||
Returned Value None. | |||
Parameters
|
clearTimeout( ) | NN 2 IE 3 DOM n/a | ||
clearTimeout(timeoutID) Turns off the timeout delay counter referenced by the timeoutID parameter. See setTimeout( ) for how to initiate such a delay. | |||
Returned Value None. | |||
Parameters
|
close( ) | NN 2 IE 3 DOM n/a |
Closes the current window. Navigator does not allow the main window to be closed from a subwindow without receiving the user's explicit permission from a security dialog box. | |
Returned Value None. | |
Parameters None. |
confirm( ) | NN 2 IE 3 DOM n/a | ||
confirm(message) Displays a dialog box with a message and two clickable buttons. One
button indicates a Because this method returns a Boolean value, you can use this method inside a condition expression: if (confirm("Reset the entire form?")) { document.forms[0].reset( ) } | |||
Returned Value Boolean value: true | false. | |||
Parameters
|
disableExternalCapture( ), enableExternalCapture( ) | NN 4 IE n/a DOM n/a |
With signed scripts and the user's permission, a script can capture events in other windows or frames that come from domains other than the one that served the document with event-capturing scripts. | |
Returned Value None. | |
Parameters None. |
execScript( ) | NN n/a IE 4 DOM n/a | ||||
execScript(expressionList [, language]) Evaluates one or more script expressions in any scripting language embedded in the browser. Expressions must be contained within a single string; multiple expressions are delimited with semicolons: window.execScript("var x = 3; alert(x * 3)") The default script language is JavaScript. If you need to see results of the script execution, provide for the display of resulting data in the script expressions. The execScript( ) method itself returns no value. | |||||
Returned Value None. | |||||
Parameters
|
find( ) | NN 4 IE n/a DOM n/a | ||||||
find(searchString [, matchCase[, searchUpward]]) Searches the document body text for a string and selects the first matching string. Optionally, you can specify whether the search should be case sensitive or search upward in the document. With the found text selected, you can use the document.getSelection( ) method to grab a copy of the found text. You don't, however, have nearly the dynamic content abilities afforded by Internet Explorer 4's TextRange object (for Win32). | |||||||
Returned Value Boolean value: true if a match was found; false if not. | |||||||
Parameters
|
focus( ) | NN 3 IE 4 DOM n/a |
Brings the window to the front of all regular browser windows and fires the onFocus event (in IE). If another window had focus at the time, that other window receives an onBlur event. | |
Returned Value None. | |
Parameters None. |
forward( ) | NN 4 IE n/a DOM n/a |
Navigates one step forward through the history list of the window or frame. If the forward history has no entries, no action takes place. | |
Returned Value None. | |
Parameters None. |
handleEvent( ) | NN 4 IE n/a DOM n/a | ||
handleEvent(event) Instructs the object to accept and process the event whose specifications are passed as the parameter to the method. The object must have an event handler for the event type to process the event. | |||
Returned Value None. | |||
Parameters
|
home( ) | NN 4 IE n/a DOM n/a |
Navigates to the URL designated as the home page for the browser.
This is the same as the user clicking on the | |
Returned Value None. | |
Parameters None. |
moveBy( ) | NN 4 IE n/a DOM n/a | ||||
moveBy(deltaX, deltaY) A convenience method that shifts the location of the window by specified pixel amounts along both axes. To shift along only one axis, set the other value to zero. Positive values for deltaX shift the window to the right; negative values to the left. Positive values for deltaY shift the window downward; negative values upward. | |||||
Returned Value None. | |||||
Parameters
|
moveTo( ) | NN 4 IE n/a DOM n/a | ||||
moveTo(x, y) Convenience method that shifts the location of the current window to a specific coordinate point. The moveTo( ) method uses the screen coordinate system. | |||||
Returned Value None. | |||||
Parameters
|
open( ) | NN 2 IE 3 DOM n/a | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
open(URL, windowName[, windowFeatures]) Opens a new window (without closing the original one). You can specify a URL to load into that window or set that parameter to an empty string to allow scripts to document.write( ) into that new window. The windowName parameter lets you assign a name that can be used by TARGET attributes. This name is not to be used in script references as frame names are. Instead, a script reference to a subwindow must be to the window object returned by the window.open( ) method. Therefore, if your scripts must communicate with a window opened in this manner, it is best to save the returned value as a global variable so that future statements can use it. A potential problem with subwindows is that they can be buried under the main window if the user clicks on the main window (or a script gives it focus). Any script that opens a subwindow should also include a focus( ) method for the subwindow (in Navigator 3 and later, and in IE 4 and later) to make sure it comes to the front in case it is already open. Subsequent invocations of the window.open( ) method whose windowName parameter is the same as an earlier call automatically address the previously opened window, even if it is underneath the main window. The optional third parameter gives you control over various physical attributes of the subwindow. The windowFeatures parameter is a single string consisting of a comma-delimited list (without spaces between items) of attribute/value pairs: newWindow = window.open("someDoc.html","subWind", "statusbar,menubar,HEIGHT=400,WIDTH=300) newWindow.focus( ) By default, all window attributes are turned on and the subwindow
opens to the same size that the browser would use to open a new
window from the | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Returned Value Window object reference. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Parameters
|
print( ) | NN 4 IE n/a DOM n/a |
Starts the printing process for the window or frame. A user must
still confirm the print dialog box to send the document to the
printer. This method is the same as clicking the | |
Returned Value None. | |
Parameters None. |
prompt( ) | NN 2 IE 3 DOM n/a | ||||
prompt(message, defaultReply) Displays a dialog box with a message, a one-line text entry field,
and two clickable buttons. The message should urge the user to enter
a specific kind of answer. One button indicates a | |||||
Returned Value When clicking the | |||||
Parameters
|
releaseEvents( ) | NN 4 IE n/a DOM n/a | ||
releaseEvents(eventTypeList) The opposite of window.captureEvents( ), this method turns off event capture at the window level for one or more specific events named in the parameter list. | |||
Returned Value None. | |||
Parameters
|
resizeBy( ) | NN 4 IE n/a DOM n/a | ||||
resizeBy(deltaX, deltaY) A convenience method that shifts the width and height of the window by specified pixel amounts. To adjust along only one axis, set the other value to zero. Positive values for deltaX make the window wider; negative values make the window narrower. Positive values for deltaY make the window taller; negative values make the window shorter. The top and bottom edges remain fixed; only the right and bottom edges are moved. | |||||
Returned Value None. | |||||
Parameters
|
resizeTo( ) | NN 4 IE n/a DOM n/a | ||||
resizeTo(x, y) Convenience method that adjusts the height and width of the window to specific pixel sizes. The top and left edges of the window remain fixed, while the bottom and right edges move in response to this method. | |||||
Returned Value None. | |||||
Parameters
|
routeEvent( ) | NN 4 IE n/a DOM n/a | ||
routeEvent(event) Used inside an event handler function, this method directs Navigator to let the event pass to its intended target object. | |||
Returned Value None. | |||
Parameters
|
scroll( ) | NN 3 IE 4 DOM n/a | ||||
scroll(x, y) Sets the scrolled position of the document inside the current window or frame. To return the document to its unscrolled position, set both parameters to zero. | |||||
Returned Value None. | |||||
Parameters
|
scrollBy( ) | NN 4 IE 4 DOM n/a | ||||
scrollBy(deltaX, deltaY) Scrolls the document in the window by specified pixel amounts along both axes. To adjust along only one axis, set the other value to zero. Positive values for deltaX scroll the document upward (so the user sees content lower in the document); negative values scroll the document downward. Positive values for deltaY scroll the document to the left (so the user sees content to the right in the document); negative values scroll the document to the right. Scrolling does not continue past the zero coordinate points (except in Navigator 4 for the Macintosh). | |||||
Returned Value None. | |||||
Parameters
|
scrollTo( ) | NN 4 IE n/a DOM n/a | ||||
scrollTo(x, y) Scrolls the document in the window to a specific scrolled position. | |||||
Returned Value None. | |||||
Parameters
|
setInterval( ) | NN 4 IE 4 DOM n/a | ||||||||
setInterval(expression, msecs[, args | language]) Starts a timer that continually invokes the expression every msecs. Other scripts can run in the time between calls to expression. This method is useful for starting animation sequences that must reposition an element along a path at a fixed rate of speed. The expression might be a function that moves the element by a fixed pixel distance along one axis. The function would be invoked at an interval set by the msecs parameter. This method returns an ID that should be saved as a global variable and be available as the parameter for the clearInterval( ) method to stop the looping timer. Navigator and Internet Explorer diverge in the use of the third parameter. Navigator lets you pass one or more parameters (as a comma-delimited list in a string) for the function acting as the expression parameter. Internet Explorer lets you specify the scripting language of the expression (if it is not the default JavaScript). | |||||||||
Returned Value Integer acting as an identifier. | |||||||||
Parameters
|
setTimeout( ) | NN 2 IE 3 DOM n/a | ||||||||
setTimeout(expression, msecs[, args | language]) Starts a one-time timer that invokes the expression after a delay of msecs. Other scripts can run while the browser waits to invoke the expression. This method returns an ID that should be saved as a global variable and be available as the parameter for the clearTimeout( ) method to stop the timer before it expires and invokes the expression. Navigator and Internet Explorer diverge in the use of the third parameter. Navigator lets you pass one or more parameters (as a comma-delimited list in a string) for the function acting as the expression parameter. Internet Explorer lets you specify the scripting language of the expression (if it is not the default JavaScript). The setTimeout( ) method can be made to behave like the setInterval( ) method in some constructions. If you place a setTimeout( ) method as the last statement of a function and direct the method to invoke the very same function, you can create looping execution with a timed delay between executions. This is how earlier browsers (before the setInterval( ) method was available) scripted repetitive tasks, such as displaying updated digital clock displays in form fields or the status bar. | |||||||||
Returned Value Integer acting as an identifier. | |||||||||
Parameters
|
showHelp( ) | NN n/a IE 4 DOM n/a | ||
showHelp(URL) Displays a | |||
Returned Value None. | |||
Parameters
|
showModalDialog( ) | NN n/a IE 4 DOM n/a | ||||||
showModalDialog(URL[, arguments[, features]]) Displays a special window that remains atop all browser windows until the user explicitly closes the dialog window. This kind of window is different from the browser windows generated with the window.open( ) method. A modal dialog has no scriptable relationship with its opening window once the dialog window is opened. All values necessary for displaying content must be in the HTML document that loads into the window or be passed as parameters. The modal dialog may then have a script set its returnValue property, which becomes the value returned to the original script statement that opened the modal dialog box as the returned value of the showModalDialog( ) method. You can pass arguments to the modal dialog by creating a data structure that best suits the data. For a single value, a string will do. For multiple values, you can create a string with a unique delimiter between values, or create an array and specify the array as the second parameter for the showModalDialog( ) method. A script in the document loaded into the modal dialog can then examine the window.dialogArguments property and parse the arguments as needed for its scripting purposes. See the dialogArguments property for an example. The third optional parameter lets you set physical characteristics of the dialog window. These characteristics are specified in a CSS-style syntax. Dimensions for dialogWidth, dialogHeight, dialogLeft, and dialogTop should be specified in pixels. An example of a call to a modal dialog is as follows: var answer = window.showModalDialog("subDoc.html",argsVariable, "dialogWidth:300px; dialogHeight:200px; center:yes") None of the third parameter characteristics are recognized by the Macintosh version of Internet Explorer 4, which creates a full-size modal dialog. | |||||||
Returned Value The value (if any) assigned to the window.returnValue property in the document loaded into the modal dialog window. | |||||||
Parameters
|
stop( ) | NN n/a IE 4 DOM n/a |
Halts the download of external data of any kind. This method is the
same as clicking the browser's | |
Returned Value None. | |
Parameters None. |
frames[ ] | NN 2 IE 3 DOM n/a |
An array of frames defined in the window. Typically, this is used within a reference to a window that contains a framesetting document and, therefore, has frames nested within. | |
Syntaxparent.frames(index).objectPropertyOrMethod top.frames(index).objectPropertyOrMethod |